<html>
<head>
<title>WFS - OGC WFS service</title>
</head>

<body bgcolor="#ffffff">

<h1>WFS - OGC WFS service</h1>

(GDAL/OGR >= 1.8.0)<p>

This driver can connect to a OGC WFS service. It supports WFS 1.0.0 and WFS 1.1.0 protocols. GDAL/OGR must be built with Curl support in order to the
WFS driver to be compiled. Usually WFS requests return results in GML format, so the GML driver should generally be set-up for read support
(thus requiring GDAL/OGR to be built with Xerces or Expat support). It is sometimes possible to use alternate underlying formats when the server supports them
(such as OUTPUTFORMAT=json).<p>

The driver supports read-only services, as well as Transactionnal ones (WFS-T).<p>

<h2>Dataset name syntax</h2>

The minimal syntax to open a WFS datasource is : <i>WFS:http://path/to/WFS/service</i> or <i>http://path/to/WFS/service?SERVICE=WFS</i><p>

Additionnal optional parameters can be specified such as <i>TYPENAME</i>, <i>VERSION</i>, <i>MAXFEATURES</i> as specified in WFS specification.<p>

The name provided to the TYPENAME parameter must be exactly the layer name reported by OGR,
in particular with its namespace prefix when its exists. Note: starting with GDAL 1.10, several type names can be provided and separated by comma.<p>

It is also possible to specify the name of an XML file whose content matches the following syntax
(the &lt;OGRWFSDataSource&gt element must be the first bytes of the file):
<pre>
&lt;OGRWFSDataSource&gt;
    &lt;URL&gt;http://path/to/WFS/service[?OPTIONAL_PARAMETER1=VALUE[&amp;amp;OPTIONNAL_PARAMETER2=VALUE]]&lt;/URL&gt;
&lt;/OGRWFSDataSource&gt;
</pre><p>

Note: the URL must be XML-escaped, for example the <i>&amp;</i> character must be written as <i>&amp;amp;</i><p>

At the first opening, the content of the result of the <i>GetCapabilities</i> request will be appended to the file, so that it can be cached
for later openings of the dataset. The same applies for the <i>DescribeFeatureType</i> request issued to discover the field definition of each layer.<p>

The service description file has the following additional elements as
immediate children of the <tt>OGRWFSDataSource</tt> element that may be optionally
set.<p>

<ul>
<li> <b>Timeout</b>: The timeout to use for remote service requests.  If not provided, the libcurl default is used.
<li> <b>UserPwd</b>: May be supplied with <i>userid:password</i> to pass a
userid and password to the remote server.
<li> <b>HttpAuth</b>: May be BASIC, NTLM or ANY to control the authentication scheme to be used.
<li> <b>Version</b>:  Set a specific WFS version to use (either 1.0.0 or 1.1.0).
<li> <b>PagingAllowed</b>: Set to ON if paging must be enabled. See "Request paging" section.
<li> <b>PageSize</b>: Page size when paging is enabled. See "Request paging" section.
<li> <b>BaseStartIndex</b>: (OGR &gt;= 1.10) Base start index when paging is enabled. See "Request paging" section.
</ul>

<h2>Request paging</h2>

Before OGR 1.10, when reading the first feature from a layer, the whole layer content will be fetched from the server.<p>

Some servers (such as MapServer >= 6.0) support a vendor specific option, STARTINDEX, that allow to do the requests per "page",
and thus to avoid downloading the whole content of the layer in a single request. The OGR WFS client will use paging when the OGR_WFS_PAGING_ALLOWED
configuration option is set to ON. The page size (number of features fetched in a single request) is limited to 100 by default.
It can be changed by setting the OGR_WFS_PAGE_SIZE configuration option.<br>
WFS 1.1 specification has clarified that the first feature in paging is at index 0. But some server implementations of WFS 1.1
have considered that it was at index 1 (including MapServer &lt;= 6.2). Starting with OGR 1.10, the default base start index is 0,
as mandated by the specification. The OGR_WFS_BASE_START_INDEX configuration option can however be set to 1 to be compatible
with the server implementations that considered the first feature to be at index 1.<br>
Those 3 options (OGR_WFS_PAGING_ALLOWED, OGR_WFS_PAGE_SIZE, OGR_WFS_BASE_START_INDEX) can also be set in a WFS XML description
file with the elements of similar names (PagingAllowed, PageSize, BaseStartIndex).<p>

Starting with OGR 1.10, the WFS driver will read the GML content as a stream instead as a whole file, which will improve
interactivity and help when the content cannot fit into memory. This can be turned off by setting the OGR_WFS_USE_STREAMING
configuration option to NO if this is not desirable (for example, when iterating several times on a layer that can fit into memory).
When streaming is enabled, GZip compression is also requested. It has been observed that some WFS servers, that cannot do on-the-fly
compression, will cache on their side the whole content to be sent before sending the first bytes on the wire. To avoid this,
you can set the CPL_CURL_GZIP configuration option to NO.<p>

<h2>Filtering</h2>

The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes its best effort to do the same for attribute
filters set with SetAttributeFilter() when possible (turning OGR SQL language into OGC filter description). When this is not possible,
it will default to client-side only filtering, which can be a slow operation because involving fetching all the features from the servers.<p>

<h2>Write support / WFS-T</h2>

The WFS-T protocol only eanbles the user to operate at feature level. No datasource, layer or field creations are possible.<p>

Write support is only enabled when the datasource is opened in update mode.<p>

The mapping between the operations of the WFS Transaction service and the OGR concepts is the following :
<ul>
<li>OGRFeature::CreateFeature() &lt;==&gt; WFS insert operation</li>
<li>OGRFeature::SetFeature() &lt;==&gt; WFS update operation</li>
<li>OGRFeature::DeleteFeature() &lt;==&gt; WFS delete operation</li>
</ul>

Lock operations (LockFeature service) are not available at that time.<p>

There are a few caveouts to keep in mind. OGR feature ID (FID) is an integer based value, whereas WFS/GML
gml:id attribute is a string. Thus it is not always possible to match both values. The WFS driver exposes
then the gml:id attribute of a feature as a 'gml_id' field.<p>

When inserting a new feature with CreateFeature(), and if the command is successfull, OGR will fetch the
returned gml:id and set the 'gml_id' field of the feature accordingly. It will also try to set the OGR FID
if the gml:id is of the form layer_name.numeric_value. Otherwise the FID will be left to its unset default value.<p>

When updating an existing feature with SetFeature(), the OGR FID field will be ignored. The request issued
to the driver will only take into account the value of the gml:id field of the feature. The same applies for
DeleteFeature().<p>

<h2>Write support and OGR transactions</h2>

The above operations are by default issued to the server synchronously with the OGR API call. This however
can cause performance penalties when issuing a lot of commands due to many client/server exchanges.<p>

It is possible to surround those operations between OGRLayer::StartTransaction() and OGRLayer::CommitTransaction().
The operations will be stored into memory and only executed at the time CommitTransaction() is called.<p>

The drawback for CreateFeature() is that the user cannot know which gml:id have been assigned to the inserted
features. A special SQL statement has been introduced into the WFS driver to workaround this : by issuing
the "SELECT _LAST_INSERTED_FIDS_ FROM layer_name" (where layer_name is to be replaced with the actual layer_name)
command through the OGRDataSource::ExecuteSQL(), a layer will be returned with as many rows
with a single attribue gml_id as the count of inserted features during the last commited transaction.<p>

Note : currently, only CreateFeature() makes use of OGR transaction mechanism. SetFeature() and DeleteFeature()
will still be issued immediately.

<h2>Special SQL commands</h2>

The following SQL / pseudo-SQL commands passed to OGRDataSource::ExecuteSQL() are specific of the WFS driver :<p>

<ul>

<li><p>"DELETE FROM layer_name WHERE expression" : this will result into
a WFS delete operation. This can be a fast way of deleting one or several features. In particularly, this
can be a faster replacement for OGRLayer::DeleteFeature() when the gml:id is known, but the feature has not
been fetched from the server.</p></li>

<li><p>"SELECT _LAST_INSERTED_FIDS_ FROM layer_name" : see above paragraph.</p></li>

</ul>

Currently, any other SQL command will be processed by the generic layer, meaning client-side only processing.
Server side spatial and attribute filtering must be done through the SetSpatialFilter() and SetAttributeFilter()
interfaces.<p>

<h2>Special layer : WFSLayerMetadata</h2>

<p>(OGR >= 1.9.0)</p>

<p>A "hidden" layer called "WFSLayerMetadata" is filled with records with metadata for each WFS layer.</p>

<p>Each record contains a "layer_name", "title" and "abstract" field, from the document returned by GetCapabilities.</p>

<p>That layer is returned through GetLayerByName("WFSLayerMetadata").</p>

<h2>Special layer : WFSGetCapabilities</h2>

<p>(OGR >= 1.9.0)</p>

<p>A "hidden" layer called "WFSGetCapabilities" is filled with the raw XML result of the GetCapabilities request.</p>

<p>That layer is returned through GetLayerByName("WFSGetCapabilities").</p>

<h2>Examples</h2>

<li>
Listing the types of a WFS server :
<pre>
ogrinfo -ro WFS:http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap
</pre>
<p>

<li>
Listing the types of a WFS server whose layer structures are cached in a XML file:
<pre>
ogrinfo -ro mswfs_gmap.xml
</pre>
<p>

<li>
Listing the features of the popplace layer, with a spatial filter :
<pre>
ogrinfo -ro WFS:http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap popplace -spat 0 0 2961766.250000 3798856.750000
</pre>

<li>
Retrieving the features of gml:id "world.2" and "world.3" from the tows:world layer :
<pre>
ogrinfo "WFS:http://www.tinyows.org/cgi-bin/tinyows" tows:world -ro -al -where "gml_id='world.2' or gml_id='world.3'"
</pre>

<li>
Display layer metadata (OGR >= 1.9.0):
<pre>
ogrinfo -ro -al "WFS:http://v2.suite.opengeo.org/geoserver/ows" WFSLayerMetadata
</pre>

<p>

<h2>See Also</h2>

<ul>
<li> <a href="http://www.opengeospatial.org/standards/wfs">OGC WFS Standard</a><p>
<li> <a href="drv_gml.html">GML driver documentation</a></a><p>
</ul>

</body>
</html>
